[Back]

Rhapsody Developer Release Copyright © 1998 by Apple Computer, Inc. All Rights Reserved.

Rhapsody Developer Release Notes:
Java APIs for the Yellow Box

The Java APIs for the core Yellow Box frameworks rest upon the foundation of Apple's Java/Objective-C integration technology (also known as the "Java Bridge"). This technology allows you to access the full potential of the Yellow Box frameworks using Java code and without having to write any Objective-C code. The bridge even allows you to subclass Objective-C objects in Java; in addition, using the bridging tools, you can wrap your own Objective-C code to make it accessible to Java applications.

In the first Developer Release, the Java APIs for the Application and Foundation frameworks were distributed in their alpha form. They have since undergone many changes and are now considerably more robust and finalized. In addition, most of the limitations that were present in Developer Release 1 have been removed. Using these APIs, you can access virtually all of the classes and protocols that make up the Application and Foundation frameworks.

The alpha versions of the APIs are still shipping with the current release (Developer Release 2), but they will be removed in the next release. They have already been removed from the current release of Yellow Box for Windows.

The current release provides a script to facilitate the conversion of application sources from the alpha APIs to the new APIs. The script does not provide complete coverage, but it will take care of most of the more straightforward cases, freeing you from some tedious conversion work. You can find the script and instructions on how to use it in /System/Developer/Java/Conversion/AlphaToYellow. Be sure to make a copy of your source directory before you apply the conversion, as the script works in place. Once you have run the scripts, trying to compile your program should pinpoint the remaining areas where conversion is still needed.

Note: On Yellow Box for Windows systems, whenever installed Rhapsody directories and files are referenced in this release note, substitute the Yellow Box for Windows installation directory for /System. For example, in the above example, substitute installed_dir/Developer/Java/Conversion/AlphaToYellow for /System/Developer/Java/Conversion/AlphaToYellow.

Changes Since Developer Release 1

• The packages for the Java APIs have new names names: com.apple.yellow.application and com.apple.yellow.foundation. (The alpha packages were named com.apple.alpha.app and com.apple.alpha.core.)

  In addition, the same class and interface names are used in the Objective-C and Java APIs; thus the Objective-C prefixes are retained (NSApplication instead of Application, EOQualifier instead of Qualifier, etc).

• Some method names are now overloaded to allow the default method-name mapping to work where applicable. For instance, replaceCharactersInRange:withAttributedString: and replaceCharactersInRange:withString: are now both represented as replaceCharactersInRange() in the Java APIs.
  
  
• The APIs provide mutable versions of the classes representing the four structs used in Yellow Box APIs (NSSize, NSPoint, NSRect, NSRange). The structs are mapped to the immutable or mutable counterparts on the Java side depending on the usage. If passed by value, the mapping is to the immutable version of the class. If passed by reference, with the purpose of getting a value back, the mapping is to the mutable version of the class. Finally, if passed by reference, but as an array, a custom mapping of the method is provided to convert the array appropriately to the Java side. New typedefs (NSRectPointer, NSRangeArray, and so on) were added to the Objective-C APIs to distinguish these two cases.

  Examples:

  -(NSDictionary)attributesAtIndex:(int)index effectiveRange:(NSRangePointer)range maps to
NSDictionary attributesAtIndex(int index, NSMutableRange range)

  void NSRectFillList(const NSRect *rects, int count) maps to
  void fillRectList(NSRect[] rects)

  Along the same lines, mutable versions of other classes (for example, NSDictionary) are used in APIs which pass these classes by reference in order to get a value back from the caller.

• To expose Objective-C APIs that take dictionaries which can contain the four basic structs (NSRect, NSPoint, NSSize, and NSRange) stored in NSValues, the setObjectForKey() method in NSDictionary in Java now checks to see whether the object is a instance of a class corresponding to these structs. These are converted to an NSValue before being stored in the dictionary. In addition objectForKey() performs the reverse mapping. This allows the storage of these kinds of values in NSDictionaries to happen naturally from both Java and Objective-C. Note that the NSNumber to Number conversion already happens in all cases.

  Examples of this include NSScreen's deviceDescription(), which returns a dictionary, and NSAttributedString's RTFFromRange(), which takes a dictionary as an argument.

  Two limitations of this feature are:

  1. The appropriate NSValue constructor should be used on the Objective-C side to put the structs in NSValues (valueWithRect: instead of valueWithBytes:objCType:); otherwise the automatic conversion won't take place.
     
     
  2. The conversion is implemented in NSDictionary only and not in the other collection classes.

   

• The fields of NSRect, NSSize, NSPoint, and NSRange are no longer public. You will need to use the methods to access or change the fields. This allows for different implementations of these classes.
  
  
• NSStringReference and NSMutableStringReference have been added to the Java APIs to allow the efficient representation of strings stored on the Objective-C side. These classes basically provide a way to wrap the NSString and NSMutableString classes rather than morph them to Java's String. In addition, they provide some functionality not available in Java's String and StringBuffer classes.

  Note that in general morphing is the right thing to do: You want to communicate strings in Java using Java's built-in java.lang.String class. Like NSString, this class stores a string of Unicode characters and provides API to deal with them. Thus most of the Yellow Box API in Java still takes or returns String, which is automatically converted to and from an NSString.

• The graphics functions in the Application Kit are now exposed as static methods in the class NSGraphics.
  
  
• Java's URL class is used as a means to refer to files in some APIs. For example, NSImage now provides the constructor NSImage(URL) in addition to the constructors taking file name as a String. Similarly, you can use the NSOpenPanel method URLs() to get back an array of URLs that represent the files selected by the user. Although these methods currently work only with URLs representing local files, they will soon work with other types of URLs. In addition, additional APIs that take or return URLs will be added throughout the frameworks where appropriate.
  
  
• Some classes in Foundation are no longer exposed, mainly because the same functionality is provided in the native Java APIs. Examples include NSFileManager, NSFileHandle, NSTask, NSThread, NSValue, and NSScanner.
  
  
• Most of the functionality in NSProcessInfo has been folded into NSSystem.
  
  
• The Objective-C NSCalendarDate class is named NSGregorianDate on the Java side. (It doesn't morph; the name just changes.)
  
  
• Additional utility methods have been added to NSPathUtilities: fileAttributes(), setFileAttributes(), pathFromURL(), URLWithPath(), and searchPathForDirectoriesInDomains(). These cover functionality available in Objective-C through functions or unexposed classes.
  
  
• Use NSPropertyListSerialization to read and write the property list classes (NSData, NSString, NSDictionary, and NSArray).
  
  
• NSAutoreleasePool methods push() and pop() are exposed in Java. They should rarely be needed.
  
  
• NSDecimalNumber, which was not exposed in Developer Release 1, is now morphed to BigNumber in Java.
  
  
• NSDictionary, NSArray, and so on now return enumerators which implement the Java Enumeration interface.
  
  
• It is now possible to access the image data in an NSBitmapImageRep as a byte array.

Other Notes

• Java does not provide a feature parallel to Objective-C's categories. The Yellow Box Java APIs expose the functionality afforded by categories in Objective-C in several ways. One way is simply to fold the functionality into the base class: For instance, NSAttributedString methods provided in a category in the Application Kit are declared in Java in the base NSAttributedString class in Foundation. In other cases the methods are exposed in other, related classes: For instance, the NSBundle method loadNibNamed(), which is added by the Application Kit, is available in NSApplication in Java.
  
  
• Classes and methods which need to be public for some reason but which should be not considered a part of the public API are prefixed with an underbar. Thus, all classes and interfaces in com.apple.yellow.foundation._private should be considered private and not used in your applications. Similarly, com.apple.yellow.application._NSObsoleteMenuItemProtocol is also private and should not be used.
  
  
• Delegate and notification methods are declared using inner interfaces, for instance, NSWindow.Delegate and NSWindow.Notifications. Given that these methods are almost always optional, classes which act as delegates do not need to declare themselves to "implement" these interfaces. Data sources are declared similarly (for instance, NSTableView.DataSource). One difference with data sources is that the methods are not optional, and thus the data source should declare that it implements the interface.
  
  
• Most creation and initialization methods in the Yellow Box classes are exposed as constructors in Java. Thus, instead of [NSView initWithFrame:rect], you use NSView(rect) to create views. This of course is the most natural way for Java, although sometimes the set of constructors might seem confusing. For instance, NSAttributedString provides the following constructors:

  NSAttributedString(String); (from a string)
  NSAttributedString(String, NSDictionary); (from a string and attributes)
  NSAttributedString(URL, NSMutableDictionary); (from the specified file, returning document properties)
  NSAttributedString(NSData, NSMutableDictionary); (from the specified file contents, returning document properties)
  NSAttributedString(NSFileWrapper, NSMutableDictionary); (from the specified file contents, returning document properties)
  NSAttributedString(NSData, URL, NSMutableDictionary); (from the specified HTML file contents and base URL, returning doc properties)

  In some cases, multiple initialization methods have been mapped to a single constructor in Java with multiple arguments; for instance, NSImage's initByReferencingFile: and initWithContentsOfFile: both map to NSImage(String, boolean), with the boolean indicating whether to reference (YES) or not (NO). Note that use of URLs to represent files also eliminates some of these cases.

  Finally, in other cases, static methods are used instead of constructors. This not only reduces the confusion associated with having many constructors, it also allows substitution of objects if necessary. NSColor is an example of this, with methods such as colorWithCalibratedRGB(), colorWithDeviceCMYK(), blackColor(), scrollBarColor(), and so on.

• In the /System/Developer/Examples directory, you can find the sources to TextEdit, which is written in Java using the Yellow Box APIs. This is the same TextEdit application shipping in /System/Applications.
  
  
• You can use WrapIt (in the /System/Developer/Applications directory) to create Java mappings for your own Objective-C classes or frameworks. Please refer to the WrapIt release notes.
  
• You can use JavaBrowser (also in the /System/Developer/Applications directory) to look at the classes and interfaces provided in Java packages available on the system.

Known Problems in This Release

• Objects in C can be referenced weakly, that is, without an explicit retain. If an object is created in Java, and passed across the bridge into Objective-C, and it is not retained by anyone on the Objective-C side, the object's proxy will get released, causing the weak references on the Objective-C side to be invalidated, thereby causing invalid memory access. One way to work around this is to ensure that such objects are referenced strongly (that is, retained) in the Objective-C side; you can assure this by putting such objects into an NSArray. TextEdit does this with its Document objects.